W08-2. Service 와 Gateway API - 실습 가이드

8주차 실습: Service 로 묶고, Gateway API 로 도메인 주소 공개하기

실습 목표 (45분)

  • ClusterIP Service 를 만들고, 요청이 Pod 3개로 나눠 가는 것을 확인한다.
  • NodePort / LoadBalancer 를 만들어 보고, Docker Desktop 에서의 동작 차이를 확인한다.
  • Envoy Gateway 를 설치하고 http://guestbook.localhost 로 방명록을 공개한다.
  • 도메인에 따라 다른 앱으로 보내는 라우팅을 해 본다.

시작 전 확인

  • Kubernetes running, 컨텍스트 docker-desktop
  • 작업 폴더: macOS cd ~/docker-study/k8s / Windows cd "$HOME\docker-study\k8s"
  • 7주차 deployment.yaml 이 v2, replicas 3 인 상태로 있어야 합니다. 지웠다면 다시 적용합니다.
    kubectl apply -f deployment.yaml
    kubectl get pods
    
  • 브라우저: Chrome 또는 Edge 권장 (*.localhost 주소 사용)

실습 내용 시간
1 ClusterIP Service 와 로드밸런싱 8분
2 Service 는 Pod 를 따라간다 4분
3 NodePort 와 LoadBalancer 7분
4 Envoy Gateway 설치 5분
5 Gateway + HTTPRoute 로 공개 8분
6 도메인별 라우팅 6분
7 메모리 저장의 한계 체험 4분
8 정리 3분

실습 1. ClusterIP Service 와 로드밸런싱

1-1. service.yaml

VS Code 로 k8s 폴더에 service.yaml 을 만듭니다.

apiVersion: v1
kind: Service
metadata:
  name: guestbook
spec:
  type: ClusterIP
  selector:
    app: guestbook
  ports:
    - port: 80
      targetPort: 8000
kubectl apply -f service.yaml
kubectl get service guestbook

출력 예시:

NAME        TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)   AGE
guestbook   ClusterIP   10.96.134.220   <none>        80/TCP    0s

1-2. Service 가 찾은 Pod 목록 (EndpointSlice)

kubectl get endpointslices -l kubernetes.io/service-name=guestbook
kubectl get pods -o wide

출력 예시: ENDPOINTS 의 IP 3개가 Pod 3개의 IP 와 같습니다.

NAME              ADDRESSTYPE   PORTS   ENDPOINTS                             AGE
guestbook-jcbh9   IPv4          8000    10.244.0.32,10.244.0.33,10.244.0.34   0s

1-3. 클러스터 안에서 접속해 보기

ClusterIP 는 클러스터 안에서만 접속됩니다. 테스트용 Pod 를 하나 띄워 두고 그 안에서 요청을 보냅니다.

kubectl run study-client --image=alpine:3.24 -- sleep 3600
kubectl wait --for=condition=Ready pod/study-client --timeout=60s

같은 주소(http://guestbook)로 6번 요청합니다.

kubectl exec study-client -- sh -c "for i in 1 2 3 4 5 6; do wget -qO- http://guestbook/healthz; echo; done"

출력 예시: hostname 이 여러 Pod 로 바뀌어 나옵니다.

{"hostname":"guestbook-5f994cddb4-lftb5","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-7fqvb","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-lftb5","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-lftb5","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-7fqvb","status":"ok","version":"v2"}
{"hostname":"guestbook-5f994cddb4-8kqk4","status":"ok","version":"v2"}
Service 가 요청을 Pod 3개로 나눠 보냈습니다

5주차 Compose 에서 --scale web=3 이 포트 충돌로 실패했던 것을, Kubernetes 는 Service 하나로 해결합니다. 순서는 무작위라 사람마다 다르게 나옵니다.

1-4. 이름이 IP 로 바뀌는 것 확인 (DNS)

kubectl exec study-client -- nslookup guestbook.default.svc.cluster.local

출력 예시 (끝부분): Service 의 CLUSTER-IP 가 나옵니다.

Name:	guestbook.default.svc.cluster.local
Address: 10.96.134.220

짧은 이름(nslookup guestbook)으로 하면 alpine 의 nslookup 이 여러 도메인을 차례로 시도하다가 NXDOMAIN 을 함께 출력하기도 합니다. 위처럼 전체 이름으로 확인하세요. wget http://guestbook 처럼 실제로 접속할 때는 짧은 이름으로 잘 됩니다.


실습 2. Service 는 Pod 를 따라간다

kubectl scale deployment guestbook --replicas=5
kubectl get endpointslices -l kubernetes.io/service-name=guestbook

출력 예시: 5개로 늘어난 Pod 가 자동으로 목록에 들어갑니다.

NAME              ADDRESSTYPE   PORTS   ENDPOINTS                                         AGE
guestbook-jcbh9   IPv4          8000    10.244.0.32,10.244.0.33,10.244.0.34 + 2 more...   3m

다시 3개로 돌립니다(파일 기준).

kubectl apply -f deployment.yaml
kubectl get endpointslices -l kubernetes.io/service-name=guestbook

Service 설정은 한 번도 고치지 않았습니다. 라벨(app=guestbook)만 맞으면 Pod 가 늘든 줄든, 롤링 업데이트로 바뀌든 Service 가 알아서 따라갑니다.


실습 3. NodePort 와 LoadBalancer

3-1. NodePort

service-nodeport.yaml

apiVersion: v1
kind: Service
metadata:
  name: guestbook-np
spec:
  type: NodePort
  selector:
    app: guestbook
  ports:
    - port: 80
      targetPort: 8000
      nodePort: 30080
kubectl apply -f service-nodeport.yaml
kubectl get service guestbook-np

출력 예시:

NAME           TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
guestbook-np   NodePort   10.96.249.217   <none>        80:30080/TCP   5s

브라우저에서 http://localhost:30080 을 열어 보세요. → 열리지 않습니다.

왜 안 될까요?

NodePort 는 노드(서버)의 포트를 엽니다. Docker Desktop(kind)의 노드는 노트북 안의 컨테이너라서, 노드에 열린 30080 이 노트북의 30080 으로 연결되지 않습니다.
실제 서버로 만든 클러스터라면 서버IP:30080 으로 접속됩니다.

노드 IP 를 확인하고, 클러스터 안(테스트 Pod)에서 노드 IP:30080 으로 접속해 봅니다.

kubectl get nodes -o wide

INTERNAL-IP 열의 주소 중 하나(예: 172.23.0.4)를 아래에 넣습니다.

kubectl exec study-client -- wget -qO- http://172.23.0.4:30080/healthz

출력 예시:

{"hostname":"guestbook-5f994cddb4-lftb5","status":"ok","version":"v2"}

노드의 30080 으로 들어온 요청이 Service 를 거쳐 Pod 로 갔습니다. 어느 노드의 IP 로 보내도 똑같이 동작합니다.

3-2. LoadBalancer

service-lb.yaml

apiVersion: v1
kind: Service
metadata:
  name: guestbook-lb
spec:
  type: LoadBalancer
  selector:
    app: guestbook
  ports:
    - port: 8090
      targetPort: 8000
kubectl apply -f service-lb.yaml
kubectl get service guestbook-lb

출력 예시: 몇 초 뒤 EXTERNAL-IP 가 채워집니다. 처음에는 <pending> 일 수 있습니다.

NAME           TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)          AGE
guestbook-lb   LoadBalancer   10.96.198.149   172.23.0.5    8090:32164/TCP   16s

브라우저에서 http://localhost:8090 → 방명록 v2 가 보입니다.

EXTERNAL-IP 로는 안 되고 localhost 로 됩니다

  • 172.23.0.5 는 Docker Desktop 내부 네트워크의 주소라 노트북 브라우저에서는 접속되지 않습니다.
  • 대신 Docker Desktop 이 LoadBalancer 를 localhost:포트 로 연결해 줍니다(실제 확인).
  • 클라우드(EKS, NKS 등)에서는 EXTERNAL-IP 자리에 클라우드 로드밸런서의 진짜 공인 주소가 붙습니다.
  • PORT(S) 의 8090:32164 처럼, LoadBalancer 는 NodePort 도 자동으로 엽니다(타입의 포함 관계).

실습용 두 Service 는 지웁니다.

kubectl delete -f service-nodeport.yaml -f service-lb.yaml

실습 4. Envoy Gateway 설치

Gateway API 의 구현체인 Envoy Gateway 를 설치합니다. Gateway API 의 규격 정의(CRD)도 함께 설치됩니다.

kubectl apply --server-side -f https://github.com/envoyproxy/gateway/releases/download/v1.9.2/install.yaml

출력 예시 (끝부분): 많은 줄이 serverside-applied 로 나옵니다.

...
job.batch/eg-gateway-helm-certgen serverside-applied
mutatingwebhookconfiguration.admissionregistration.k8s.io/envoy-gateway-topology-injector.envoy-gateway-system serverside-applied

준비될 때까지 기다립니다(처음에는 이미지를 받느라 1~2분 걸릴 수 있음).

kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available
kubectl get pods -n envoy-gateway-system

출력 예시:

deployment.apps/envoy-gateway condition met
NAME                            READY   STATUS      RESTARTS   AGE
eg-gateway-helm-certgen-w85qh   0/1     Completed   0          15s
envoy-gateway-6579bbfdf-q8xhd   1/1     Running     0          15s
--server-side 는 꼭 붙이세요

설치 파일이 매우 커서, 이 옵션 없이 적용하면 실제로 이런 에러가 납니다(확인함).

... "httproutes.gateway.networking.k8s.io" is invalid: metadata.annotations: Too long: may not be more than 262144 bytes

실습 5. Gateway + HTTPRoute 로 공개

5-1. gateway.yaml: 시공사(GatewayClass)와 정문(Gateway)

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: eg
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: study-gateway
spec:
  gatewayClassName: eg
  listeners:
    - name: http
      protocol: HTTP
      port: 80

--- 는 한 파일에 YAML 문서 여러 개를 넣을 때 쓰는 구분선입니다.

kubectl apply -f gateway.yaml
kubectl wait --timeout=3m gateway/study-gateway --for=condition=Programmed
kubectl get gatewayclass
kubectl get gateway

출력 예시:

gateway.gateway.networking.k8s.io/study-gateway condition met
NAME   CONTROLLER                                      ACCEPTED   AGE
eg     gateway.envoyproxy.io/gatewayclass-controller   True       18s
NAME            CLASS   ADDRESS      PROGRAMMED   AGE
study-gateway   eg      172.23.0.6   True         18s
뒤에서 일어난 일

Gateway 를 만들자 Envoy Gateway 가 Envoy 프록시 Pod 와 이를 외부에 여는 LoadBalancer Service 를 자동으로 만들었습니다.

kubectl get pods,services -n envoy-gateway-system

envoy-default-study-gateway-... 이름의 Pod 와 LoadBalancer 타입 Service(포트 80)가 보입니다. 실습 3-2 에서 본 것처럼 Docker Desktop 이 이것을 localhost:80 으로 연결합니다.

5-2. httproute.yaml: 안내표

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: guestbook
spec:
  parentRefs:
    - name: study-gateway
  hostnames:
    - "guestbook.localhost"
  rules:
    - backendRefs:
        - name: guestbook
          port: 80
부분 의미
parentRefs 어느 정문(Gateway) 에 붙일지
hostnames 어떤 도메인으로 들어온 요청인지
backendRefs 어느 Service 의 몇 번 포트로 보낼지 (실습 1의 guestbook:80)
kubectl apply -f httproute.yaml
kubectl get httproute

출력 예시:

NAME        HOSTNAMES                 AGE
guestbook   ["guestbook.localhost"]   5s

5-3. 브라우저로 접속

브라우저에서 http://guestbook.localhost 를 엽니다. → 방명록 v2 🎉

명령어로도 확인할 수 있습니다.

macOS:

curl http://guestbook.localhost/healthz

Windows (PowerShell): curl 이 아니라 curl.exe 로 칩니다.

curl.exe http://guestbook.localhost/healthz

출력 예시:

{"hostname":"guestbook-5f994cddb4-8kqk4","status":"ok","version":"v2"}
전체 경로가 연결됐습니다

브라우저 → guestbook.localhost:80 → Gateway(Envoy) → HTTPRoute 규칙 → Service guestbook → Pod 3개 중 하나

접속이 안 될 때

  • Safari 등 일부 브라우저는 *.localhost 를 처리하지 못할 수 있습니다. Chrome / Edge 를 쓰세요.
  • Windows PowerShell 의 curl 은 Invoke-WebRequest 의 별칭이라 *.localhost 를 찾지 못합니다(The remote name could not be resolved). curl.exe 로 치세요.
  • 노트북의 80번 포트를 다른 프로그램(로컬 웹 서버 등)이 쓰고 있으면 연결되지 않습니다.


실습 6. 도메인별 라우팅

정문 하나로 두 번째 앱도 공개해 봅니다. nginx 를 hello 라는 이름으로 띄웁니다.

kubectl create deployment hello --image=nginx:1.30-alpine
kubectl expose deployment hello --port=80
kubectl rollout status deployment/hello

kubectl create deployment, kubectl expose 는 Deployment 와 Service 를 명령으로 빠르게 만드는 방법입니다(테스트용).

httproute-hello.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: hello
spec:
  parentRefs:
    - name: study-gateway
  hostnames:
    - "hello.localhost"
  rules:
    - backendRefs:
        - name: hello
          port: 80
kubectl apply -f httproute-hello.yaml
kubectl get httproute

출력 예시:

NAME        HOSTNAMES                 AGE
guestbook   ["guestbook.localhost"]   2m
hello       ["hello.localhost"]       4s
브라우저 주소 결과
http://guestbook.localhost 방명록
http://hello.localhost Welcome to nginx!
http://nothing.localhost 404 (안내표에 없는 도메인)
입구는 하나, 앱은 여러 개

외부로 열린 곳은 Gateway 의 80번 하나뿐인데, 도메인을 보고 다른 앱으로 나눠 보냈습니다. 앱마다 LoadBalancer(외부 IP, 비용)를 만들 필요가 없습니다.


실습 7. 메모리 저장의 한계 체험

http://guestbook.localhost 에서 글을 하나 남기고, 새로고침을 여러 번 해 보세요. HOSTNAME 과 글 목록을 같이 보세요.

관찰 예시 (실제로 확인한 결과): 응답한 Pod 끝 5글자 : 보이는 글 개수

8kqk4:1  8kqk4:1  8kqk4:1  8kqk4:1  8kqk4:1  8kqk4:1  lftb5:0  7fqvb:0  8kqk4:1
글이 보였다 안 보였다 합니다. 왜일까요?

방명록은 지금 메모리 저장 모드입니다. 글은 글을 받은 Pod 의 메모리에만 있고, 다른 Pod 에는 없습니다. Service 가 요청을 여러 Pod 로 나눠 보내니 어느 Pod 가 응답하느냐에 따라 결과가 달라집니다.
👉 해결: 모든 Pod 가 같은 DB 를 보게 하면 됩니다. 다음 주에 PostgreSQL 을 Kubernetes 에 올리고 방명록을 연결합니다.

(새로고침이 같은 Pod 로만 가서 차이가 안 보이면, 브라우저를 닫았다 열거나 다른 브라우저로 열어 보세요. 연결을 재사용하면 같은 Pod 로 가기 쉽습니다.)


실습 8. 정리

테스트용 Pod 와 hello 앱은 지웁니다.

kubectl delete pod study-client
kubectl delete -f httproute-hello.yaml
kubectl delete service hello
kubectl delete deployment hello
남겨 둘 것 (9·10주차에 계속 씀)

  • Envoy Gateway (envoy-gateway-system Namespace)
  • gateway.yaml 의 GatewayClass / Gateway
  • httproute.yaml, service.yaml, deployment.yaml

확인: kubectl get gateway,httproute,service,deployment


자주 나는 문제와 해결

증상 원인 해결
Service 의 ENDPOINTS 가 비어 있음 selector 의 라벨이 Pod 라벨과 다름 kubectl get pods --show-labels 로 비교
wget: can't connect to remote host ... Connection refused targetPort 가 틀림 (예: 80 으로 씀) 방명록은 8000
wget: bad address 'guestbook' Service 이름 오타, 또는 다른 Namespace kubectl get svc 로 이름 확인
localhost:30080 이 안 열림 Docker Desktop(kind)의 정상 동작 실습 3-1 참고 (LoadBalancer 나 Gateway 사용)
LoadBalancer 의 EXTERNAL-IP 가 계속 <pending> 클러스터가 막 생성됨, 또는 kubeadm 방식 잠시 기다리기. Docker Desktop 에서 kind 방식인지 확인
metadata.annotations: Too long: may not be more than 262144 bytes (설치 중) --server-side 없이 apply --server-side 붙여서 다시
Gateway 의 PROGRAMMED 가 False Envoy Gateway 가 아직 준비 중 kubectl get pods -n envoy-gateway-system 확인 후 기다리기
guestbook.localhost 가 안 열림 브라우저가 *.localhost 미지원, 80 포트 사용 중, HTTPRoute 미적용 Chrome/Edge 사용, kubectl get httproute 확인, curl.exe -H "Host: guestbook.localhost" http://localhost/ 로 테스트

오늘 쓴 명령어 정리

명령어 하는 일
kubectl apply -f service.yaml / kubectl get service Service 만들기 / 목록
kubectl get endpointslices -l kubernetes.io/service-name=이름 Service 가 찾은 Pod 목록
kubectl run study-client --image=alpine:3.24 -- sleep 3600 테스트용 Pod
kubectl exec study-client -- wget -qO- http://이름/경로 클러스터 안에서 접속 테스트
kubectl exec study-client -- nslookup 이름.default.svc.cluster.local DNS 확인
kubectl apply --server-side -f <URL> 큰 설치 파일 적용
kubectl wait --for=condition=... 대상 준비될 때까지 기다리기
kubectl get gatewayclass / gateway / httproute Gateway API 오브젝트 확인
kubectl create deployment 이름 --image=... / kubectl expose deployment 이름 --port=80 빠르게 만들기 (테스트용)

복습 과제

확인 퀴즈

  1. Pod 의 IP 로 직접 접속하지 않고 Service 를 쓰는 이유는?
  2. Service 는 어떤 Pod 로 트래픽을 보낼지 어떻게 정하나요?
  3. port: 80, targetPort: 8000 은 각각 무엇의 포트인가요?
  4. ClusterIP, NodePort, LoadBalancer 의 차이는?
  5. Ingress-NGINX 는 어떻게 되었고, 새로 설계할 때는 무엇을 쓰나요?
  6. Gateway API 의 GatewayClass, Gateway, HTTPRoute 는 각각 무슨 역할인가요?
  7. 실습 7에서 글이 보였다 안 보였다 한 이유와 해결 방법은?

도전 과제 (선택)

  1. httproute.yaml 의 rules 에 경로 조건을 넣어, http://guestbook.localhost/healthz 만 받게 바꿔 보세요. 다른 경로는 어떻게 되나요?
      rules:
        - matches:
            - path:
                type: PathPrefix
                value: /healthz
          backendRefs:
            - name: guestbook
              port: 80
    
    확인 후에는 원래 httproute.yaml 로 되돌려 apply 하세요.
  2. Pod 하나의 라벨을 app=debug 로 바꾼 뒤(7주차 실습 3) EndpointSlice 를 다시 보세요. 그 Pod 가 Service 목록에서도 빠졌나요? 확인 후 그 Pod 는 지우세요.
다음 주 예고: 9주차 ConfigMap · Secret · PV/PVC

방명록의 DB 주소와 비밀번호를 ConfigMap / Secret 으로 넘기고, PostgreSQL 데이터를 PersistentVolumeClaim 에 저장합니다. 그러면 Pod 3개가 같은 DB 를 보게 되어 실습 7의 문제가 사라집니다. 5주차 Compose 로 했던 일을 Kubernetes 로 옮기는 주차입니다.


네비게이션

이전 목록 다음
◀ 8주차 강의 노트 목록으로 9주차 강의 노트 ▶